/*
 ------------------------------------------------------------------------------
 Copyright (C) 2006-2007 Team Blur.

 This file is part of the Quantum Engine source code.

 The Quantum Engine source code is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or (at your
 option) any later version.

 The Quantum Engine source code is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 more details.

 You should have received a copy of the GNU General Public License along with
 the Quantum Engine source code; if not, write to the Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 ------------------------------------------------------------------------------
*/


#ifndef __CMDSYSTEM_H__
#define __CMDSYSTEM_H__


/*
 ==============================================================================

 Console command execution and command text buffering:

 Any number of commands can be added in a frame from several different sources.
 Most commands come from either key bindings or console line input, but remote
 servers can also send across commands and entire text files can be executed.
 The + command line arguments are also added to the command buffer.

 Command execution takes a NULL terminated string, breaks it into tokens, then
 searches for a command or variable that matches the first token.

 ==============================================================================
*/

// Adds a command and the function to call for it.
// If function is NULL, the command will be forwarded to the server instead of
// executed locally.
// The description parameter can be NULL if you don't want it.
void			Cmd_AddCommand (const char *name, cmdFunction_t function, const char *description);

// Removes a command
void			Cmd_RemoveCommand (const char *name);

// Command completion using a callback for each match
void			Cmd_CompleteCommand (const char *partial, void (*callback)(const char *));

// Returns the number of arguments
int				Cmd_Argc (void);

// Returns the given argument.
// Will return an empty string, not NULL, if arg < 0 or arg >= argc, so string
// operations are always safe.
const char *	Cmd_Argv (int arg);

// Returns a string containing argv[start] to argv[end]. Specifying 1 for start
// and -1 for end will return all the arguments. Specifying 0 for start will
// also include the command.
// If tokenized is false, the original, unmodified command string will be
// returned (ignoring the end parameter).
const char *	Cmd_Args (int start, int end, bool tokenized);

// Parses the given string into command line tokens. Does not need to be \n
// terminated.
// The text is copied to a separate buffer and 0 characters are inserted in the
// appropriate place. The argv array will point into this temporary buffer.
// $CVars will be expanded unless they are in a quoted string.
void			Cmd_TokenizeString (const char *text);

// Adds command text at the end of the command buffer. Does not add a final \n.
void			Cmd_AppendText (const char *text);

// Adds command text at the beginning of the command buffer. Adds a final \n.
void			Cmd_InsertText (const char *text);

// This can be used in place of either Cmd_AppendText or Cmd_InsertText
void			Cmd_ExecuteText (cmdExec_t exec, const char *text);

// Pulls off \n or ; terminated lines of text from the command buffer and
// executes the commands. Stops when the buffer is empty.
// Normally called once per frame, but may be explicitly invoked.
// Do not call inside a command function!
void			Cmd_ExecuteBuffer (void);

// Initializes the cmd system
void			Cmd_Init (void);

// Shuts down the cmd system
void			Cmd_Shutdown (void);


#endif	// __CMDSYSTEM_H__
